package com.mrogrape.util;

import java.util.List;

/**
 * 此接口标识一个可查找对象的源。
 * 
 * @author  Ice Spring
 * @version 0.9.20110831
 *
 * @param <K> 查找的键的类型。
 * @param <V> 返回的值的类型。
 */
public interface Findable<K, V> {


	/**
	 * 查找并返回全部符合键的对象，如果没有查找到结果则返回空集。
	 * 
	 * <p>
	 * 三个查找方法都会重置结果集。
	 * 
	 * <p>
	 * 此方法并不强制实现，但如果结果集不会很大则推荐实现以实现更好的用户体验。但三种
	 * 查找方法至少要实现一种。
	 * 
	 * @param findWhat 需要查找的内容。
	 * @return 符合查询条件的结果的数量。
	 */
	List<V> find(K findWhat);

	/**
	 * 查找并返回固定数目的符合键的对象，如果没有查找到结果则返回空集。
	 * 
	 * <p>
	 * 三个查找方法都会重置结果集。
	 * 
	 * <p>
	 * 此方法并不强制实现，但如果结果集可能很大则推荐实现以实现更好的用户体验。但三种
	 * 查找方法至少要实现一种。
	 * 
	 * @param findWhat 需要查找的内容。
	 * @param limit    返回的结果对象数目的上限。
	 * @return 结果的数量。
	 */
	List<V> find(K findWhat,int limit);

	/**
	 * 查找并返回指定范围内全部符合键的对象。
	 * 
	 * <p>
	 * 三个查找方法都会重置结果集。
	 * 
	 * <p>
	 * 这个方法指定的范围是假定的结果范围，所以在查找时不需要缓存全部的结果，这对数据库
	 * 和大型文档查询有重要意义。配合{@link #getResultCount()}方法可以方便的实现结果
	 * 分页浏览。如果查找时在指定的范围内没有结果对象，则返回空集。
	 * 
	 * <p>
	 * 此方法并不强制实现，但如果结果集可能很大则推荐实现以实现更好的用户体验。但三种
	 * 查找方法至少要实现一种。
	 * 
	 * @param findWhat    需要查找的内容。
	 * @param beginIndex  查找起始索引值,结果包含。
	 * @param endIndex    查找结束索引值，结果不包含。
	 * @return 结果的数量。
	 */
	List<V> find(K findWhat,int beginIndex,int endIndex);

	/**
	 * 返回查找结果集，这个结果集与使用相应的查找方法时返回的结果集相同。
	 * 
	 * <p>
	 * 在最近一次执行过{@link #clearResult()}后如果从未执行过任何查找方法，则返回null。
	 * 
	 * @return
	 */
	List<V> getFoundResult();

	/**
	 * 返回符合键的全部对象的数目。
	 * 
	 * <p>
	 * 在最近一次执行过{@link #clearResult()}后如果从未执行过任何查找方法，此方法将返回-1.
	 * 
	 * <p>
	 * <b>注意：</b>这个方法返回的是查找源中符合查找键的全部结果的数目，而无论使用的
	 * 何种查找方法。也就是说，即使使用的是限制返回结果大小的查找方法，此方法返回的值
	 * 也是全部符合查找键的结果对象的数目。
	 * 
	 * <p>
	 * 此方法并不强制实现，但如果结果集可能很大则推荐实现以实现更好的用户体验。但三种
	 * 查找方法至少要实现一种。
	 * 
	 * @return 符合键的对象的数目。
	 */
	int getResultCount();

	/**
	 * 返回符合查询条件的第一个结果对象。
	 * 
	 * <p>
	 * 在最近一次执行过{@link #clearResult()}后如果从未执行过任何查找方法，则返回null。
	 * 
	 * @return 第一个结果。
	 */
	V firstResult();

	/**
	 * 返回符合查询条件的最后一个结果对象。
	 * 
	 * <p>
	 * 在最近一次执行过{@link #clearResult()}后如果从未执行过任何查找方法，则返回null。
	 * 
	 * @return 最后一个结果。
	 */
	V lastResult();

	/**
	 * 返回下一个符合查询条件的结果对象并移动结果查看指针。
	 * 
	 * <p>
	 * 在最近一次执行过{@link #clearResult()}后如果从未执行过任何查找方法，或已经到达
	 * 结果集尾部，则返回null。
	 * 
	 * @return 下一个结果
	 */
	V nextResult();

	/**
	 * 返回当前指针所查看的结果对象。
	 * 
	 * <p>
	 * 在最近一次执行过{@link #clearResult()}后如果从未执行过任何查找方法，则返回null。
	 * 
	 * @return 当前结果对象。
	 */
	V currentResult();

	/**
	 * 返回前一个符合查询条件的结果对象并移动结果查看指针。
	 * 
	 * <p>
	 * 在最近一次执行过{@link #clearResult()}后如果从未执行过任何查找方法，或已经到达
	 * 结果集头部，则返回null。
	 * 
	 * 
	 * @return 前一个结果对象
	 */
	V previousResult();

	/**
	 * 返回指定索引处的结果。
	 * 
	 * @param index 需要返回的结果的索引，此索引需要符合查询条件。
	 * @return 该索引处的结果对象。
	 */
	V indexOfResult(int index);

	/**
	 * 清空查询结果。
	 */
	void clearResult();

	/**
	 * 重新按照最近一次使用的查询方法进行查找。
	 * 
	 * @return 查询结果集的大小。
	 */
	int refind();
}
